home *** CD-ROM | disk | FTP | other *** search
/ Mission 3 / Mission 3.zip / Mission 3.iso / demovers / texel / zusatz / gscript / gscript.txt < prev   
Text File  |  1997-11-14  |  27KB  |  965 lines
  1.                 Fernsteuern von GEM-Applikationen mit
  2.  
  3.                               GEMScript
  4.  
  5.                        09.11.1997 (Release 1.0)
  6.  
  7.                                  von
  8.  
  9.               Thomas Much, Holger Weets, Manfred Lippert
  10.  
  11.  
  12. Inhaltsverzeichnis
  13. ==================
  14.  
  15.  1  Einleitung
  16.  
  17.  2  Das Konzept im Überblick
  18.  
  19.  3  GEM-Nachrichten
  20.     3.1  Initialisierung
  21.          3.1.1  GS_REQUEST
  22.          3.1.2  GS_REPLY
  23.          3.1.3  Die GS_INFO-Struktur
  24.     3.2  Abmeldung
  25.          3.2.1  GS_QUIT
  26.     3.3  Fernsteuerung
  27.          3.3.1  GS_COMMAND
  28.          3.3.2  GS_ACK
  29.     3.4  Makros
  30.          3.4.1  GS_OPENMACRO
  31.          3.4.2  GS_MACRO
  32.          3.4.3  GS_WRITE
  33.          3.4.4  GS_CLOSEMACRO
  34.  
  35.  4  Nachstarten eines GS-Interpreters
  36.  
  37.  5  Standard-GS-Kommandos
  38.     5.1  Close
  39.     5.2  Copy
  40.     5.3  Cut
  41.     5.4  Delete
  42.     5.5  GetFront
  43.     5.6  New
  44.     5.7  Open
  45.     5.8  Paste
  46.     5.9  Print
  47.     5.10  Quit
  48.     5.11  Save
  49.     5.12  SaveAs
  50.     5.13  SelectAll
  51.     5.14  ToFront
  52.     5.15  Undo
  53.  
  54.  6  Weitere GS-Kommandos
  55.     6.1  Exec
  56.     6.2  CheckApp
  57.  
  58.  7  Parameter
  59.     7.1  Leere Parameter
  60.     7.2  Datei
  61.     7.3  Datei+Pfad
  62.     7.4  Script
  63.  
  64. Anhang
  65. ======
  66.  
  67.  A  History
  68.  
  69.  B  Kontakt
  70.  
  71.  
  72.  
  73. 1  Einleitung
  74. *************
  75.  
  76. GEMScript ist ein Protokoll, um GEM-Applikationen fernzusteuern. Das
  77. Protokoll selbst ist sehr einfach gehalten, so daß es für
  78. Programmierer kein großes Problem darstellt, GEMScript in ihren
  79. Programmen zu unterstützen.
  80.  
  81. Diese Dokumentation definiert dieses GEMScript-Protokoll und ist somit
  82. in erster Linie an Programmierer gerichtet. Wohlgemerkt handelt es
  83. sich bei GEMScript noch nicht um ein konkretes Programm, sondern nur
  84. um die Definition einer Kommunikation zwischen GEM-Programmen:
  85.  
  86. Die am häufigsten auftretende Anwendung einer Kommunikation mittels
  87. GEMScript dürfte die durch einen Script-Interpreter darstellen. Einen
  88. solchen Interpreter stellt z.B. "Scripter" von Holger Weets dar.
  89. Festgelegt durch ein Script in einer Sprache, die dieser Interpreter
  90. versteht, verschickt der Interpreter über das definierte GEMScript-
  91. Protokoll Kommandos an GEM-Programme, die dann die gewünschten
  92. Aktionen ausführen:
  93.  
  94. Natürlich können auch GEM-Programme ohne einen Script-Interpreter
  95. untereinander per GEMScript kommunizieren.
  96.  
  97. Die hohe Flexibilität des GEMScript-Protokolls eröffnet sich dadurch,
  98. daß in keinster Weise die Kommandos vorgeschrieben sind, die versendet
  99. werden. Es ist nur definiert wie Kommandos verschickt werden, nicht
  100. aber welche Kommandos dies sind.
  101.  
  102. Jede Applikation kann also ihre eigenen Kommandos bereitstellen, je
  103. nach dem, welche Fähigkeiten sie eben hat. Ein Zeichenprogramm wird
  104. beispielsweise sicher andere Kommandos bereitstellen wollen, als ein
  105. Desktop oder eine Tabellenkalkulation.
  106.  
  107. Es gibt jedoch ein paar Standard-Kommandos, die in nahezu jeder
  108. Applikation sinnvoll erscheinen, z.B. das Öffnen eines Dokumentes.
  109. Daher beschreibt diese GEMScript-Dokumentation ebenfalls einen Satz
  110. solcher Standard-GS-Kommandos, an die sich jede GEMScript-fähige
  111. Applikation - soweit möglich - halten sollte. Zwingend ist dies jedoch
  112. nicht.
  113.  
  114.  
  115.  
  116. 2  Das Konzept im Überblick
  117. ***************************
  118.  
  119. Wie im Vorwort schon erwähnt, handelt es sich bei GEMScript um eine
  120. Kommunikation zwischen GEM-Programmen, bei der Kommandos verschickt
  121. werden.
  122.  
  123. Der eigentliche Austausch basiert auf normalen AES-Nachrichten.
  124.  
  125. Das zugrundeliegende Prinzip der Kommunikation dabei ist eigentlich
  126. recht einfach:
  127.  
  128.  1. Eine Applikation, die mit einer anderen kommunizieren möchte,
  129.      meldet sich zunächst einmal bei dieser Applikation an ("Hallo!
  130.      Hier bin ich und möchte mich gerne mit dir per GEMScript
  131.      unterhalten."). Dazu gibt es die Nachrichten GS_REQUEST und
  132.      GS_REPLY.
  133.  
  134.  2. Danach kann bereits die "Session" beginnen, d.h. man schickt sich
  135.      munter Kommandos zu. Dazu gibt es die Nachrichten GS_COMMAND und
  136.      GS_ACK. Die Applikationen unterhalten sich, und sagen
  137.      gegenseitig, was zu tun ist. In den meisten Fällen läuft das
  138.      ganze recht einseitig ab, d.h. eine Applikation kommandiert, was
  139.      zu tun ist (normalerweise der Script-Interpreter) und die andere
  140.      Applikation führt es aus. Natürlich sind aber auch andere
  141.      "Gespräche" denkbar.
  142.  
  143.  3. Will sich eine Applikation nicht mehr unterhalten, meldet sie sich
  144.      einfach wieder ab ("Tschüß dann!"). Dazu gibt es die Nachricht
  145.      GS_QUIT.
  146.  
  147. Für Leute, denen das zu einfach ist, gibt es noch ein kleines
  148. Schmankerl, das man in seine GEMScript-fähigen Applikationen einbauen
  149. kann - aber nicht unbedingt muß: Die Aufnahme von Aktionen (Makros).
  150. Eine Applikation, die das unterstützt, nennt man "aufnahmefähig".
  151.  
  152. Dazu wird nun zwingend ein Script-Interpreter gebraucht, der noch dazu
  153. fähig sein muß, Kommandos aufzuzeichnen, um sie später wieder
  154. abspielen zu können. Er muß quasi selbständig Scripts erstellen,
  155. aufgrund der Informationen, die ihm eine Applikation liefert. Führt
  156. man ein solches entstandene Script zu einem späteren Zeitpunkt aus, so
  157. wiederholt die Applikation sinngemäß genau das, was sie bei der
  158. Aufnahme gemacht hat.
  159.  
  160. Hier der prinzipielle Ablauf einer Aufnahme:
  161.  
  162.  1. Der Benutzer aktiviert die Aufnahme in einer Applikation. Die
  163.      Applikation sucht daraufhin den GEMScript-Interpreter (startet
  164.      ihn gegebenenfalls nach) und initialisiert die GEMScript-
  165.      Kommunikation in gewohnter Weise mit GS_REQUEST/GS_REPLY. Meist
  166.      muß der Benutzer nun noch ein File auswählen, in der das
  167.      aufzunehmende Script landen soll.
  168.  
  169.  2. Die Applikation gibt dem Interpreter bekannt, daß sie jetzt gerne
  170.      aufnehmen möchte. Dazu existiert die Nachricht GS_OPENMACRO. Ist
  171.      der Interpreter einverstanden, schickt er GS_MACRO zurück, als
  172.      Zeichen, daß nun die Aufnahme beginnen kann.
  173.  
  174.  3. Die Applikation sendet nun alle Aktionen, die aufgenommen werden
  175.      sollen, mit der Nachricht GS_WRITE an den Interpreter. Dieser
  176.      erzeugt daraus das Script.
  177.  
  178.  4. Beendet der Benutzer die Aufnahme, so sagt die Applikation dies
  179.      dem Interpreter mit der Nachricht GS_CLOSEMACRO. Fertig.
  180.  
  181. Hat man eine Applikation erst mal GEMScript-fähig gemacht, stellt im
  182. Grunde also auch die Aufnahmefähigkeit kein großes Problem mehr dar.
  183.  
  184. Um das ganze zu vervollständigen gibt es noch eine weitere kleine
  185. Variante der Aufnahme: Die applikationsübergreifende Aufnahme.
  186.  
  187. Dazu ist eine weitere spezielle Applikation nötig, die diese Aufnahme
  188. koordiniert: Der Aufnahme-Server. Der Desktop "jinnee" funktioniert
  189. beispielsweise als ein solcher Server. Auch diese
  190. applikationsübergreifende Aufnahme sei kurz erläutert:
  191.  
  192.  1. Der Benutzer aktviert die applikationsübergreifende Aufnahme im
  193.      Aufnahme-Server. Wie bei einer normalen Aufnahme, sucht dieser
  194.      Server den GEMScript-Interpreter und initialisiert die
  195.      GEMScript-Kommunikation mit GS_REQUEST/GS_REPLY.
  196.  
  197.  2. Wie bei der normalen Aufnahme, beginnt der Server, eine Aufnahme
  198.      beim Interpreter zu starten (GS_OPENMACRO). Der Interpreter
  199.      antwortet mit GS_MACRO.
  200.  
  201.  3. Außerdem versucht der Aufnahme-Server GEMScript-Kontakt zu allen
  202.      laufenden Applikationen aufzunehmen (GS_REQUEST/GS_REPLY). Bei
  203.      Applikationen, bei denen dies geklappt hat, löst der Server quasi
  204.      "von außen" eine Aufnahme mit der Nachricht GS_MACRO aus. Sind
  205.      die Applikationen von außen aufnahmefähig, fangen sie jetzt an,
  206.      munter ihre Kommandos per GS_WRITE an den Server zu schicken.
  207.      (Für die Applikationen ist der Server in diesem Falle der
  208.      Interpreter.)
  209.  
  210.  4. Der Server sammelt alle aufzunehmenden Kommandos aller laufenden
  211.      Applikationen, kennzeichnet diese speziell (um sie später beim
  212.      Abspielen des Scripts wieder zu erkennen), und schickt diese
  213.      neuen Kommandos als "seine" aufzunehmenden Kommandos an den
  214.      Interpreter weiter. Dieser zeichnet sie im Script auf.
  215.  
  216.  4. Beendet der Benutzer die Aufnahme, unterbricht der Server die
  217.      Aufnahme bei allen Applikationen ebenfalls wieder "von außen".
  218.      Ebenso beendet er seine eigene Aufnahme beim Interpreter. (Beides
  219.      mit GS_CLOSEMACRO). Fertig.
  220.  
  221.  5. Spielt man das entstandene Script ab, so findet der Interpreter
  222.      nur Kommandos, die für den Server bestimmt sind, und schickt
  223.      diese dann auch an ihn. Der Server wiederum erkennt, daß es sich
  224.      um Kommandos anderer Applikationen handelt, und leitet sie
  225.      entsprechend einfach weiter. Hier sieht man den Vorteil, den der
  226.      Server hat, wenn es sich um ein Desktop handelt (wie im Falle
  227.      jinnee): Läuft eine Applikation beim Abspielen des Scripts nicht,
  228.      kann er diese meist ohne großen Aufwand einfach nachstarten,
  229.      sofern die Applikation im Desktop angemeldet ist.
  230.  
  231. Nach diesem Überblick der Möglichkeiten kann die konkrete
  232. Dokumentation des GEMScript-Protokolls beginnen.
  233.  
  234.  
  235.  
  236. 3  GEM-Nachrichten
  237. ******************
  238.  
  239.  
  240. 3.1  Initialisierung
  241. ====================
  242.  
  243.  
  244. 3.1.1  GS_REQUEST
  245. -----------------
  246.  
  247. Um festzustellen, ob eine Applikation GEMScript unterstützt, schickt
  248. man ihr folgende Message.
  249.  
  250. GS_REQUEST
  251. msg[0] 0x1350 (4944)
  252. msg[1] ap_id
  253. msg[2] 0
  254. msg[3]
  255.     +  Pointer auf GS_INFO-Struktur
  256. msg[4]
  257. msg[5] 0
  258. msg[6] 0
  259. msg[7] beliebige ID
  260.  
  261.  
  262. Antwort:
  263.  
  264. Wenn die Applikation GEMScript versteht, erhält man als Antwort
  265. GS_REPLY.
  266.  
  267. Man muß jede Applikation natürlich nur einmal vor dem ersten Kommando
  268. auf GEMScript testen.
  269.  
  270.  
  271. 3.1.2  GS_REPLY
  272. ---------------
  273.  
  274. GS_REPLY wird von einer GEMScript-fähigen Applikation als Antwort auf
  275. GS_REQUEST verschickt.
  276.  
  277. GS_REPLY
  278. msg[0] 0x1351 (4945)
  279. msg[1] ap_id
  280. msg[2] 0
  281. msg[3]
  282.     +  Pointer auf GS_INFO-Struktur
  283. msg[4]
  284. msg[5] 0
  285. msg[6] 0:     OK, Applikation kann GS-Kommunikation durchführen
  286.        sonst: Fehler, GS-Kommunikation derzeit nicht möglich
  287. msg[7] ID aus GS_REQUEST
  288.  
  289.  
  290. Wenn eine Applikation in msg[6] einen Fehler meldet, dürfen an sie
  291. keine weiteren GS-Nachrichten geschickt werden. Man kann aber zu einem
  292. späteren Zeitpunkt mit GS_REQUEST erneut die GEMScript-Fähigkeit
  293. erfragen.
  294.  
  295. Man beachte, daß eine Applikation mehrere GS_REQUEST-Nachrichten
  296. erhalten kann. Zum einen können verschiedene Applikationen eine
  297. Kommunikation beginnen, aber durch die ID kann eine Applikation sogar
  298. in mehreren "Sessions" gleichzeitig kommunizieren.
  299.  
  300. Ist eine Applikation nur auf eine laufende Kommunikation gleichzeitig
  301. ausgelegt (z.B. weil der aktuelle Kommunikationspartner in einer
  302. globalen Variablen vermerkt wird), so muß darauf geachtet werden, daß
  303. alle folgenden GS_REQUEST-Nachrichten korrekt abgelehnt werden, wenn
  304. bereits eine Kommunikation läuft. (Am besten mit einem Wert ungleich 0
  305. in msg[6].)
  306.  
  307.  
  308. 3.1.3  Die GS_INFO-Struktur
  309. ---------------------------
  310.  
  311.  
  312. typedef struct {
  313.    long len;       /* Länge der Struktur in Bytes                      */
  314.    int  version;   /* Versionsnummer des Protokolles beim Sender
  315.                       (z.Z. 0x0100 = 1.0)                             */
  316.    int  msgs;      /* Bitmap der unterstützten Nachrichten (GSM_xxx)   */
  317.    long ext;       /* benutzte Endung, etwa '.SIC'                     */
  318. } GS_INFO;
  319.  
  320. GSM_COMMAND = 0x0001  /* kann GS_COMMAND empfangen                     */
  321. GSM_MACRO   = 0x0002  /* kann GS_OPENMACRO, GS_WRITE und GS_CLOSEMACRO
  322.                          empfangen, GS_MACRO verschicken
  323.                          (Interpreter)                                 */
  324. GSM_WRITE   = 0x0004  /* kann GS_OPENMACRO, GS_WRITE und GS_CLOSEMACRO
  325.                          verschicken, GS_MACRO empfangen
  326.                          (aufnahmefähige Applikation)                  */
  327.  
  328. Anmerkungen zur GS_INFO-Struktur:
  329.  
  330.    ∙ Die Struktur muß per Mxalloc() im globalen Speicher alloziert
  331.      sein.
  332.  
  333.    ∙ Die Strukur darf vom Empfänger nicht verändert werden. D.h.
  334.      GS_REQUEST- und GS_REPLY-Sender müssen jeweils ihre eigene
  335.      Struktur allozieren.
  336.  
  337.    ∙ Da man nicht feststellen kann, wann der Empfänger die Struktur
  338.      ausgelesen hat, sollte sie grundsätzlich verfügbar sein. Es
  339.      empfiehlt sich daher, die Struktur am Anfang des Programmes zu
  340.      allozieren und erst am Ende wieder freizugeben.
  341.  
  342.    ∙ long belegt 32 Bit. Entspricht also auch size_t oder dem
  343.      sizeof()-Typ in Pure-C.
  344.  
  345.    ∙ int belegt 16 Bit.
  346.  
  347.    ∙ ext ist für den Interpreter gedacht. Andere Applikationen können
  348.      hier 0 eintragen.
  349.  
  350.  
  351. 3.2  Abmeldung
  352. ==============
  353.  
  354.  
  355. 3.2.1  GS_QUIT
  356. --------------
  357.  
  358. GS_QUIT sollte an den Kommunikationspartner geschickt werden, wenn
  359. eine fernsteuernde Applikation keine GS_COMMAND-Befehle mehr
  360. verschickt oder wenn eine ferngesteuerte Applikation solche
  361. Nachrichten nicht mehr auswerten kann/möchte (z.B. weil die
  362. Applikation terminiert).
  363.  
  364. GS_QUIT
  365. msg[0] 0x1354 (4948)
  366. msg[1] ap_id
  367. msg[2] 0
  368. msg[3] 0
  369. msg[4] 0
  370. msg[5] 0
  371. msg[6] 0
  372. msg[7] ID aus GS_REQUEST
  373.  
  374.  
  375. 3.3  Fernsteuerung
  376. ==================
  377.  
  378.  
  379. 3.3.1  GS_COMMAND
  380. -----------------
  381.  
  382. GS_COMMAND
  383. msg[0] 0x1352 (4946)
  384. msg[1] ap_id
  385. msg[2] 0
  386. msg[3]
  387.     +  Pointer auf Kommandozeile, s.u.
  388. msg[4]
  389. msg[5] 0
  390. msg[6] 0
  391. msg[7] ID aus GS_REQUEST
  392.  
  393. Die Kommandozeile enthält das eigentliche Kommando, gefolgt von
  394. optionalen Parametern. Kommando und Parameter sind durch ASCII #0
  395. getrennt, am Ende der Kommandozeile steht ASCII #0#0, in C-Notation
  396. also z.B.
  397.  
  398. "Kommando\0Parameter 1\0Parameter 2\0\0"
  399.  
  400. Die Kommandos müssen beim Empfänger ohne Beachtung der Groß-/
  401. Kleinschreibung ausgewertet werden. Dabei wäre es schön, wenn
  402. möglichst viele Standard-GS-Kommandos unterstützt würden.
  403.  
  404. Die Zeichenkette muß per Mxalloc() im globalen Speicher alloziert
  405. sein.
  406.  
  407. Antwort:
  408.  
  409. Als Antwort erhält man die Nachricht GS_ACK, die zum Freigeben dieses
  410. Speichers benutzt werden kann.
  411.  
  412. Siehe auch: Parameter.
  413.  
  414.  
  415. 3.3.2  GS_ACK
  416. -------------
  417.  
  418. Folgende Nachricht wird von einer GEMScript-fähigen Applikation als
  419. Antwort auf GS_COMMAND verschickt. Die fernsteuernde Applikation kann
  420. beim Empfang dieser Nachricht z.B. den Speicher vom msg[3/4] wieder
  421. freigeben.
  422.  
  423. GS_ACK
  424. msg[0] 0x1353 (4947)
  425. msg[1] ap_id
  426. msg[2] 0
  427. msg[3]
  428.     +  exakt die Werte der empfangenen GS_COMMAND-Nachricht
  429. msg[4]
  430. msg[5]
  431.     +  Ergebnis bzw. Fehlermeldung als ASCIIZZ-Text (s.u.) oder NULL
  432. msg[6]
  433. msg[7] 0: (GSACK_OK)      OK, Kommando wurde oder wird ausgeführt
  434.        1: (GSACK_UNKNOWN) Kommando unbekannt
  435.        2: (GSACK_ERROR)   Fehler (Kommando nicht ausgeführt)
  436.  
  437. Wird in msg[5/6] eine Rückgabe geliefert, liegt diese im Format wie
  438. die GS_COMMAND-Kommandozeile vor, also die einzelnen Werte durch ASCII
  439. #0 getrennt mit ASCII #0#0 am Ende des Rückgabestrings.
  440.  
  441. Antwort:
  442.  
  443. Wenn die auswertende Applikation in msg[5/6] ein Ergebnis der Funktion
  444. oder eine Fehlerbeschreibung liefert (also einen Wert ungleich NULL),
  445. muß die fernsteuernde Applikation folgende Antwort zurückschicken. Die
  446. auswertende Applikation kann dann ihrerseits den Ergebnisspeicher
  447. freigeben.
  448.  
  449. GS_ACK
  450. msg[0] 0x1353 (4947)
  451. msg[1] ap_id
  452. msg[2] 0
  453. msg[3] 0
  454. msg[4] 0
  455. msg[5]
  456.     +  exakt die Werte der empfangenen GS_ACK-Nachricht
  457. msg[6]
  458. msg[7] 0
  459.  
  460. Anmerkungen zum Rückgabestring:
  461.  
  462. Der Rückgabewert eines Kommandos sollte immer über msg[5]+msg[6]
  463. zurückgegeben werden, man sollte nicht msg[7] dafür "mißbrauchen".
  464. Dies gilt vor allem für Kommandos, die wahr oder falsch zurückliefern.
  465. Sofern das Kommando korrekt ausgeführt werden konnte, sollte man bei
  466. "wahr" einen beliebigen nicht-leeren Rückgabestring (z.B. "1")
  467. zurückliefern, bei "false" empfiehlt sich Leerstring oder Nullpointer.
  468.  
  469. Dies ist z.B. für den Interpreter "Scripter" von Holger sehr
  470. praktisch, denn dann können True/False-Kommandos bequem durch
  471. folgendes Script abgefragt werden:
  472.  
  473. if (kommando(...))
  474. {
  475.         /* wahr */
  476. }
  477. else
  478. {
  479.         /* falsch */
  480. }
  481.  
  482. Würde das Ergebnis ist msg[7] zurückgeliefert, müßte man im Beispiel
  483. "Scripter" folgendes schreiben:
  484.  
  485. kommando(...)
  486. if (errno == 0)
  487. {
  488.         /* wahr */
  489. }
  490. else
  491. {
  492.         /* falsch */
  493. }
  494.  
  495.  
  496. 3.4  Makros
  497. ===========
  498.  
  499.  
  500. 3.4.1  GS_OPENMACRO
  501. -------------------
  502.  
  503. GS_OPENMACRO
  504. (App->Interpreter)
  505. msg[0] 0x1355 (4949)
  506. msg[1] ap_id
  507. msg[2] 0
  508. msg[3]
  509.     +  Pointer auf Dateinamen, unter dem das Script gespeichert werden soll
  510. msg[4]
  511. msg[5] 0
  512. msg[6] 0
  513. msg[7] 0
  514.  
  515. Eine Applikation will vom Script-Interpreter aufgenommen werden. Als
  516. Antwort bekommt sie GS_MACRO.
  517.  
  518. Der Interpreter sollte über die Environment-Variable GEMSCRIPT gesucht
  519. und ggf. auch nachgestartet werden.
  520.  
  521. Die Datei-Endung für Scripte kann die Applikation vom Interpreter über
  522. die GS_INFO-Struktur bei GS_REPLY erfahren. Diese Endung wird evtl.
  523. für den Fileselector benötigt, den man in den meisten Fällen vor einer
  524. Aufnahme aufrufen wird.
  525.  
  526. Zusammenfassung des Ablaufs einer Aufnahme:
  527.  
  528.    ∙ Interpreter suchen und ggf. nachstarten. (GEMSCRIPT-Variable)
  529.  
  530.    ∙ Beim Interpreter anmelden (GS_REQUEST)
  531.  
  532.    ∙ Interpreter anwortet mit GS_REPLY (liefert GS_INFO)
  533.  
  534.    ∙ Fileselector aufrufen (Extension aus GS_INFO vom Interpreter)
  535.  
  536.    ∙ Aufnahme mit GS_OPENMACRO starten
  537.  
  538.    ∙ Interpreter liefert GS_MACRO
  539.  
  540.    ∙ Aufnahme per GS_WRITE/GS_ACK
  541.  
  542.    ∙ Am Ende Aufnahme mit GS_CLOSEMACRO beenden
  543.  
  544.  
  545. 3.4.2  GS_MACRO
  546. ---------------
  547.  
  548. GS_MACRO
  549. (Interpreter->App)
  550. msg[0] 0x1356 (4950)
  551. msg[1] ap_id
  552. msg[2] 0
  553. msg[3]
  554.     +  exakt die Werte der empfangenen GS_OPENMACRO-Nachricht
  555.        oder NULL bei Aufnahme-Aufforderung
  556. msg[4]
  557. msg[5] ID (am einfachsten das Dateihandle) zur Identifizierung des Scripts
  558. msg[6] 0: Datei ist geöffnet, Aufzeichnung kann beginnen; sonst: Fehler
  559. msg[7] 0
  560.  
  561. Zu beachten: GS_MACRO kann auch ohne ein vorheriges GS_OPENMACRO
  562. auftreten. msg[3/4] ist dann NULL.
  563.  
  564. Dieser Fall soll quasi Aufforderung zur Aufnahme betrachtet werden,
  565. wodurch z.B. eine applikationsübergreifende Aufnahme durch einen
  566. externen Aufnahme-Server möglich ist. Die Applikation wird also
  567. aufgefordert, ab jetzt alle Aktionen per GS_WRITE an den Aufnahme-
  568. Server (der das GS_MACRO gesendet hat) zu schicken.
  569.  
  570. Will oder kann die Applikation gerade nicht aufnehmen, so muß sie ein
  571. GS_CLOSEMACRO zurücksenden.
  572.  
  573. Zusammenfassung des Ablaufs einer erzwungenen Aufnahme:
  574.  
  575.    ∙ Aufnahmeserver (z.B. jinnee) meldet sich mit GS_REQUEST bei der
  576.      Applikation an. Applikation antwortet mit GS_REPLY.
  577.      Aufnahmeserver stellt über GS_INFO-Struktur fest, daß Applikation
  578.      GS_MACRO kann, also aufnahmefähig ist.
  579.  
  580.    ∙ Aufnahmeserver erzwingt Aufnahme mit GS_MACRO (NULL im
  581.      Dateinamen)
  582.  
  583.    ∙ Applikation antwortet entweder mit GS_CLOSEMACRO (Ablehnung) oder
  584.      nimmt einfach mit GS_WRITE/GS_ACK die Aktionen auf.
  585.  
  586.    ∙ Aufnahmeserver oder Applikation beendet Aufnahme mit
  587.      GS_CLOSEMACRO
  588.  
  589.  
  590. 3.4.3  GS_WRITE
  591. ---------------
  592.  
  593. GS_WRITE
  594. (App->Interpreter)
  595. msg[0] 0x1357 (4951)
  596. msg[1] ap_id
  597. msg[2] 0
  598. msg[3]
  599.     +  Pointer auf Kommandozeile (wie bei GS_COMMAND)
  600. msg[4]
  601. msg[5] ID aus GS_MACRO
  602. msg[6] 0
  603. msg[7] 0
  604.  
  605. Der Interpreter antwortet auf diese Nachricht wie bei GS_COMMAND mit
  606. GS_ACK, ohne allerdings in msg[5/6] ein Ergebnis zurückzuliefern.
  607.  
  608. Falls in diesem GS_ACK ein Fehler signalisiert wird, sollten keine
  609. weiteren GS_WRITE-Nachrichten verschickt werden.
  610.  
  611.  
  612. 3.4.4  GS_CLOSEMACRO
  613. --------------------
  614.  
  615. GS_CLOSEMACRO
  616. (App->Interpreter / Interpreter->App)
  617. msg[0] 0x1358 (4952)
  618. msg[1] ap_id
  619. msg[2] 0
  620. msg[3] 0
  621. msg[4] 0
  622. msg[5] ID aus GS_MACRO
  623. msg[6] 0
  624. msg[7] 0
  625.  
  626. Beendet die Aufzeichnung eines Scripts.
  627.  
  628. Zu beachten: Die Aufnahme kann von beiden Seiten beendet werden.
  629. Sowohl von der aufnehmenden Applikation selbst, als auch vom
  630. Interpreter (Aufnahme-Server bei applikationsübergreifender Aufnahme).
  631.  
  632.  
  633.  
  634. 4  Nachstarten eines GS-Interpreters
  635. ************************************
  636.  
  637. Damit Applikationen (z.B. zum Aufzeichnen von Makros) einen GS-
  638. Interpreter per appl_find() finden oder - falls ein solcher nicht
  639. läuft - nachstarten können, kann im Environment die Variable GEMSCRIPT
  640. gesetzt werden, beispielsweise
  641.  
  642.  
  643.   #_ENV GEMSCRIPT=D:\SCRIPTER\SCRIPTER.APP
  644.  
  645.  
  646.  
  647.  
  648. 5  Standard-GS-Kommandos
  649. ************************
  650.  
  651.  
  652. 5.1  Close
  653. ==========
  654.  
  655. Kommando:  Close
  656. Parameter: Datei (optional)
  657. Rückgabe:  keine
  658.  
  659. Schließt das der Datei entsprechende Fenster. Wenn keine Datei
  660. übergeben wurde, wird das oberste Fenster geschlossen. Das Kommando
  661. darf auch so implementiert sein, daß mehrere Datei-Parameter auf
  662. einmal übergeben werden können.
  663.  
  664.  
  665. 5.2  Copy
  666. =========
  667.  
  668. Kommando:  Copy
  669. Parameter: Datei (optional)
  670. Rückgabe:  keine
  671.  
  672. Kopiert die Selektion der angegebenen Datei auf das Klemmbrett. Wenn
  673. keine Datei angegeben ist, wird die Selektion des obersten Fensters
  674. verwendet.
  675.  
  676.  
  677. 5.3  Cut
  678. ========
  679.  
  680. Kommando:  Cut
  681. Parameter: Datei (optional)
  682. Rückgabe:  keine
  683.  
  684. Schneidet die Selektion der angegebenen Datei aus und schreibt sie auf
  685. das Klemmbrett. Wenn keine Datei angegeben ist, wird die Selektion des
  686. obersten Fensters verwendet.
  687.  
  688.  
  689. 5.4  Delete
  690. ===========
  691.  
  692. Kommando:  Delete
  693. Parameter: Datei (optional)
  694. Rückgabe:  keine
  695.  
  696. Schneidet die Selektion der angegebenen Datei aus. Wenn keine Datei
  697. angegeben ist, wird die Selektion des obersten Fensters verwendet.
  698.  
  699.  
  700. 5.5  GetFront
  701. =============
  702.  
  703. Kommando:  GetFront
  704. Parameter: keine
  705. Rückgabe:  Datei oder Datei+Pfad
  706.  
  707. Falls das oberste Fenster der Applikation einen Namen besitzt, mit dem
  708. es in den GS-Kommandos identifiziert werden kann, sollte dieser als
  709. Antwort auf dieses Kommando zurückgeliefert werden.
  710.  
  711.  
  712. 5.6  New
  713. ========
  714.  
  715. Kommando:  New
  716. Parameter: keine
  717. Rückgabe:  keine
  718.  
  719. Legt ein neues Dokument an.
  720.  
  721.  
  722. 5.7  Open
  723. =========
  724.  
  725. Kommando:  Open
  726. Parameter: Datei+Pfad (optional)
  727. Rückgabe:  keine
  728.  
  729. Öffnet die angegebene Datei. Wenn keine Datei übergeben wurde, sollte
  730. dem Benutzer die Dateiauswahlbox o.ä. angezeigt werden. Das Kommando
  731. darf auch so implementiert sein, daß mehrere Datei-Parameter auf
  732. einmal übergeben werden können.
  733.  
  734.  
  735. 5.8  Paste
  736. ==========
  737.  
  738. Kommando:  Paste
  739. Parameter: Datei (optional)
  740. Rückgabe:  keine
  741.  
  742. Fügt den Inhalt des Klemmbretts in die Selektion der angebenenen Datei
  743. ein. Wenn keine Datei angegeben ist, wird die Selektion des obersten
  744. Fensters verwendet.
  745.  
  746.  
  747. 5.9  Print
  748. ==========
  749.  
  750. Kommando:  Print
  751. Parameter: Datei (optional)
  752. Rückgabe:  keine
  753.  
  754. Druckt die angegebene Datei aus. Wenn keine Datei angegeben ist, wird
  755. das oberste Fenster ausgedruckt. Das Kommando darf auch so
  756. implementiert sein, daß mehrere Datei-Parameter auf einmal übergeben
  757. werden können.
  758.  
  759.  
  760. 5.10  Quit
  761. ==========
  762.  
  763. Kommando:  Quit
  764. Parameter: keine
  765. Rückgabe:  keine
  766.  
  767. Beendet die Applikation.
  768.  
  769.  
  770. 5.11  Save
  771. ==========
  772.  
  773. Kommando:  Save
  774. Parameter: Datei (optional)
  775. Rückgabe:  keine
  776.  
  777. Speichert die angegebene Datei. Wenn keine Datei übergeben wurde, wird
  778. das oberste Fenster gespeichert. Das Kommando darf auch so
  779. implementiert sein, daß mehrere Datei-Parameter auf einmal übergeben
  780. werden können.
  781.  
  782.  
  783. 5.12  SaveAs
  784. ============
  785.  
  786. Kommando:  SaveAs
  787. Parameter: Datei, Datei (optional)
  788. Rückgabe:  keine
  789.  
  790. Dieses Kommando hat mindestens einen, maximal zwei Parameter. Der
  791. erste bezeichnet den neuen Dateinamen, der zweite das zu speichernde
  792. Fenster. Wenn der zweite Parameter nicht angegeben ist, wird das
  793. oberste Fenster unter dem Dateinamen des ersten Parameters
  794. gespeichert.
  795.  
  796.  
  797. 5.13  SelectAll
  798. ===============
  799.  
  800. Kommando:  SelectAll
  801. Parameter: Datei (optional)
  802. Rückgabe:  keine
  803.  
  804. Markiert die gesamte angegebene Datei. Wenn keine Datei angegeben ist,
  805. wird das Dokument im obersten Fenster selektiert.
  806.  
  807.  
  808. 5.14  ToFront
  809. =============
  810.  
  811. Kommando:  ToFront
  812. Parameter: Datei
  813. Rückgabe:  keine
  814.  
  815. Bringt das Fenster mit der angegebenen Datei nach vorne.
  816.  
  817.  
  818. 5.15  Undo
  819. ==========
  820.  
  821. Kommando:  Undo
  822. Parameter: Datei (optional)
  823. Rückgabe:  keine
  824.  
  825. Macht die letzte Aktion in der angegebenen Datei rückgängig. Wenn
  826. keine Datei angegeben ist, wird die letzte Aktion im obersten Fenster
  827. rückgängig gemacht.
  828.  
  829.  
  830.  
  831. 6  Weitere GS-Kommandos
  832. ***********************
  833.  
  834. Im folgenden sind alle Kommandos aufgelistet, bei denen zwar eine
  835. Standardisierung Sinn macht, die aber nicht zwingend unterstützt
  836. werden müssen, oder nur von bestimmten Programmen zu unterstützen
  837. sind.
  838.  
  839.  
  840. 6.1  Exec
  841. =========
  842.  
  843. Kommando:  Exec
  844. Parameter: <Script> <Parameter>
  845. Rückgabe:  keine
  846.  
  847. Dieses Kommando muß von jedem GEMScript-Interpreter unterstützt
  848. werden. Es dient dazu, Script-Dateien auszuführen.
  849.  
  850. Mit <Script> wird die Script-Datei angegeben, dabei muß der
  851. Interpreter mindestens eine komplette Pfadangabe samt Extension
  852. verstehen.
  853.  
  854. <Parameter> (optional) steht für weitere beliebige Parameter, die an
  855. das Script weitergegeben werden, falls dies der Interpreter erlaubt.
  856.  
  857.  
  858. 6.2  CheckApp
  859. =============
  860.  
  861. Kommando:  CheckApp
  862. Parameter: Datei
  863. Rückgabe:  keine
  864.  
  865. Versucht, die angegebene Datei nachzustarten.
  866.  
  867.  
  868.  
  869. 7  Parameter
  870. ************
  871.  
  872.  
  873. 7.1  Leere Parameter
  874. ====================
  875.  
  876. Mehrere Parameter sind durch ASCII #0 getrennt, und das Ende der
  877. Kommandozeile ist mit ASCII #0#0 gekennzeichnet (siehe GS_COMMAND).
  878.  
  879. Deshalb mußte für den Sonderfall "leerer Parameter" eine Ausnahme
  880. eingeführt werden:
  881.  
  882. Leere Parameter werden durch das ASCII-Zeichen #1 gekennzeichnet, z.B.
  883.  
  884. "Kommando\0Gleich folgt ein leerer Parameter\0\1\0Gemerkt?\0\0"
  885.  
  886. Wichtig: Außerdem sind Parameter, die mit den ASCII-Zeichen #2 bis
  887. einschließlich #6 anfangen, für zukünftige Zwecke reserviert, und
  888. müssen vom Empfänger derzeit ignoriert werden!
  889.  
  890. Beispiel:
  891.  
  892. "Kommando\0Parameter 1\0\2Dieser Text wird ignoriert\0Parameter 2\0\0"
  893.  
  894.  
  895. 7.2  Datei
  896. ==========
  897.  
  898. Der Datei-Parameter bezeichnet einen Dateinamen (mit oder ohne
  899. Pfadangabe). Da einzelne Kommandos durch ASCII #0 getrennt werden,
  900. erfolgt kein (!) Quoting.
  901.  
  902. GEMScript-fähige Applikationen stellen i.d.R. mit einem solchen
  903. Parameter fest, welches Fenster von einem Kommando betroffen ist. Wenn
  904. ein direkter Vergleich von Kommando-Dateinamen und dem Fenster
  905. zugewiesenen Dateinamen keinen Erfolg bringt, sollte die Applikation
  906. nach einer möglichst großen Übereinstimmung von Teilstrings suchen.
  907.  
  908.  
  909. 7.3  Datei+Pfad
  910. ===============
  911.  
  912. Dieser Parameter bezeichnet einen Dateinamen mit absoluter Pfadangabe.
  913.  
  914.  
  915. 7.4  Script
  916. ===========
  917.  
  918. Dieser Parameter bezeichnet eine Script-Datei (für das Exec-Kommando).
  919. Es handelt sich um eine Datei-Angabe, wobei die Endung der konkreten
  920. Script-Datei auch weggelassen werden kann. Falls dia absolute
  921. Pfadangabe fehlt, muß er Interpreter in der Lage sein, die Datei zu
  922. finden (z.B. weil sie im Verzeichnis des Interpreters liegt).
  923.  
  924.  
  925.  
  926.  
  927. A  History
  928. **********
  929.  
  930.  Rev 1.0 (14.11.97)
  931.  
  932.         ∙ erste öffentliche Version
  933.  
  934.  
  935.  
  936. B  Kontakt
  937. **********
  938.  
  939.  
  940. Thomas Much, Gerwigstraße 46, D-76131 Karlsruhe, Germany
  941.  
  942. Fax:       +49 / (0)721 / 62 28 21
  943.  
  944. EMail:     Thomas Much @ KA2                 (MausNet)
  945.            Thomas_Much@ka2.maus.de
  946.            Thomas.Much@stud.uni-karlsruhe.de (Internet)
  947.  
  948.  
  949. Holger Weets, Tangastraße 45, D-26121 Oldenburg, Germany
  950.  
  951. EMail:     Holger Weets @ OL       (MausNet)
  952.            Holger_Weets@ol.maus.de (Internet)
  953.  
  954.  
  955. Manfred Lippert, Nordring 102, D-90409 Nürnberg, Germany
  956.  
  957. EMail:     Manfred Lippert @ N       (MausNet)
  958.            Manfred_Lippert@n.maus.de
  959.            ft195@fen.baynet.de       (Internet)
  960.  
  961.  
  962.  
  963.  
  964.  
  965.